۱. به گونه ای بنویسید که قابل خواندن باشد

گاهی به عنوان یک دولوپر ما فراموش می کنیم که داریم این کامنت ها را برای انسان ها می گذاریم . زبان های برنامه نویسی برای ماشین ها ساخته شده اند، بنابراین خواندن آنها برای انسان ها مشکل است، بیاییم حداقل کامنت ها را به گونه ای بنویسیم که برای انسان ها قابل خواندن باشند، نه برای ماشین ها. ببینید، منظور این نیست که برای هر قسمتی، توضیحی به اندازه قصه حسین کرد شبستری بنویسید، هدف فقط توضیح دادن نکات مهم به صورتی واضح و قابل فهم است.

function getTheMail() {
    // code here will build e-mail  
  
    /* run code if our custom sendMyMail() function call returns true 
       find sendMyMail() in /libs/mailer.class.PHP 
       we check if the user fills in all fields and message is sent! */  
    if(sendMyMail()) { return true; // keep true and display onscreen success  
    }  
}

حتی چند کلمه نوشتن هم، بهتر از هرگز ننوشتن است. زمانی که بعدا به پروژه برمی گردید و قصد دارید آن را ویرایش کنید، حتما تعجب خواهید کرد که چقدر از کد را فراموش کرده اید. زیرا پس از مدتی آنها به فراموشی سپرده می شوند. بنابراین اگر نمی توانید به تعداد زیاد کامنت های خوب و کمک کننده بگذارید، حداقل کامنت های بد و مبهم بگذارید. بدانید که چند کلمه نوشتن، بهتر از هرگز ننوشتن است.

به عنوان یک قانون، هر چند وقت یک بار دست از کد نویسی بردارید، کمی درنگ کنید و آنچه نوشته اید را توضیح دهید. از خودتان بپرسید گیج کننده ترین قسمت کد من چیست و چگونه آن را به زبان ساده و قابل فهم برای احمق‌ترین انسان ها توضیح دهم.

در پروژه هایی که فایل های مختلف داخل یک دیگر اینکلود (include) شده اند و یا از یک فانکشن خارجی (3rd party) استفاده می کنند، کامنت گذاری را فراموش نکنید. این پروژه ها گاهی بی نهایت پیچیده می شوند. پس سعی کنید همیشه کامنتی در بالای هر فایل (حتی اگر از جایی دیگر، برای کاری دیگر دانلود و به پروژه تان اضافه شده) بگذارید، تا با دیدن آن عملکرد کد را به یاد بیاورید.

۲. کمی فضا برای نفس کشیدن

واقعا نمی توانم آن طور که باید از اهمیت و فواید فضای خالی (whitespace) در کد بگویم. خصوصا این فضا برای دولوپرهایی که روی پروژه های بزرگ کار می کنند، حیاتی است. این پروژه ها گاهی حاوی صدها فایل و هر فایل دارای صدها خط کد است. در این هنگام ستون های بی پایان کد، سر شما را به درد - یا حداقل گیج - می آورد. به نظر شما عالی نیست که در این فایل ها بتوانید به سرعت قسمت های مهم کد را پیدا کنید؟

$dir1 = "/home/";                 // set main home directory  
$myCurrentDir = getCurDirr();     // set the current user directory  
$userVar = $get_username();      // current user's username

در مثال بالا من مقداری فضا بین کامنت ها و کد در هر خط گذاشته ام. هنگامی که در حال اسکرول کردن فایل هستید، این کامنت ها به خوبی دیده می شوند. جدا و تمیز بودن بلاک های کد از یکدیگر باعث می شود پیدا کردن ارورها و درست کردن آنها در میان صدها خط کد بسیار آسان تر شود.

اگر عملکرد فانکشنی مبهم است، گرچه می توانید کاری مشابه بالا (کامنت های این لاین) در داخل فانکشن ها بکنید اما این کار ممکن است کمی کدتان را بهم بریزد که در تقابل با اصل نظم است. پس توصیه می کنیم در این زمان از بلاک های توضیح مانند مثال زیر استفاده کنید:

$(document).ready(function() {  
        $('.sub').hide(); // hide sub-navigation on pageload  
  
        /** check for a click event on an anchor inside .itm div 
              prevent the default link action so the page doesn't change on click 
              access the parent element of .itm followed by the next .sub list to toggle open/close 
        **/   
  
        $('.itm a').live('click', function(e){ 
        e.preventDefault(); 
        $(this).parent().next('.sub').slideToggle('fast');  
       });  
});

در بالا یک کد جی کوییری را می بینیم که برای یک منو (menu) نوشته شده. کامنت اول که این لاین است، توضیح می دهد، کلاس sub را پنهان (hide) کرده ایم. و سپس قبل از شروع کد اصلی بلاک توضیحی نوشته و آن را نسبت به سایر نوشته ها جلوتر آورده ایم (indent). این کار متن را زیباتر و خواناتر می کند، خصوصا برای آنهایی که چیزی از کد نمی فهمند و فقط قصد خواندن کامنت ها را دارند.

۳. کامنت ها را هنگام کدنویسی بگذارید

کامنت گذاری هنگام کدنویسی یکی از بهترین عادت ها است. هیچ کس دوست ندارد پس از نوشتن یک برنامه و مطمئن شدن از کارکرد آن، به سراغ کدش برود و توضیح بنویسد. بسیاری از ما حتی می ترسیم طرف چنین کد - بدون کامنت - گیج کننده ای برویم زیرا کامنت گذاری آن زحمت زیادی می برد.

اما اگر هنگام کدنویسی، کامنت بگذارید، همه چیز در ذهن تازه است و توضیح آن آسان تر. یکی از بهترین زمان ها برای نوشتن کامنت، هنگام حل مشکل است. معمولا زمانی که دولوپرها به مشکلی برمی خورند، به عنوان اولین گزینه در اینترنت جستجو می کنند. زمانی که پاسخ را می یابند، این زمان بهترین وقت برای نوشتن یک کامنت واضح و ساده راجع به چگونگی حل مشکل است.

به علاوه، انجام این کار به عادت کامنت گذاری هنگام کدنویسی نیز کمک می کند. گاهی برگشتن و فهمیدن اینکه یک فانکشن چگونه کار می کند، حتی از نوشتن آن نیز زمانبر تر است. مطمئن باشید، با کامنت گذاری و جلوگیری از اتلاف چنین وقتی، هم تیمی ها و حتی خودتان در آینده را، بسیار خوشحال خواهید کرد.

۴. در پایان کدنویسی

ما نمی توانیم در برای مدت طولانی جلوی کامپیوتر بنشینیم و کد بنویسیم. قبلا فکر می کردیم که می شود، اما بعد متوجه شدیم که انسان به خواب هم احتیاج دارد. کد نویسی شما در طول روز، به دلایل مختلف، به زمان های کوچک تر تقسیم می شود. پس اگر باگی پیدا شده، ساعت ها با آن سروکله زده اید، خسته شده اید، قصد استراحت و ادامه کار با نیروی تازه دارید، بسیار مهم است که یک کامنت بلند و با توضیحات کامل بگذارید که در کجای کد بودید و دفعه بعد از کجا باید شروع کنید.

حتی بعد از یک خواب کوتاه، گاهی از فراموش شدن بخش زیادی از کد متعجب خواهید شد. در این زمان مشکل است تا بلافاصله کار را از سر بگیرید و کمی زمان می برد تا به سرعت کدنویسی معمول برسید. برای مثال اگر یک صفحه برای آپلود عکس طراحی می کنید و قصد دارید آن را نیمه تمام رها کنید، باید توضیح دهید که در چه مرحله از کار بوده اید. آیا عکس آپلود می شد؟ آیا در پوشه Temp قرار می گرفت؟ ممکن است هنوز فرم آپلود را نیز کامل نکرده اید، یا شاید عکس ها پس از آپلود به خوبی نمایش داده نمی شوند.

کامنت گذاری در این زمان به دو دلیل اهمیت دارد: اول اینکه بدانید کجا کار را قطع کرده اید و دفعه بعد که با نیروی تازه به سراغ کد آمدید، دقیقا بدانید به چه گیر کرده بودید (نباید این سوال برای شما ایجاد شود که «خببب کجا بودم؟»). 
دوم، برای افتراق دادن کدتان از سایر کدهایی که مشکلی ندارند و به خوبی کار می کنند. 
به خاطر داشته باشید، هنگام کامنت گذاری باید توضیح دهید «چرا دارید فلان کد را می نویسید»، نه اینکه دقیقا توضیح دهید «کد چه کاری انجام می دهد».

۵. جمع بندی

طراحی اپلیکیشن (application) ها و نرم افزارهای تحت وب بهترین تمرین برای یادگیری کامنت گذاری هستند. برای تبدیل شدن به یک دولوپر عالی فقط تمرین کدنویسی کافی نیست، باید مهارت های کامنت گذاری را نیز در خودتان تقویت کنید. کامنت گذاری با توضیح کامل، نیاز به تمرین طولانی مدت دارد، اما زمانی که آن را خوبی یاد گرفتید هرگز رهایش نخواهید کرد.

نظرات شما عزیزان:

نام :

آدرس ایمیل:

وب سایت/بلاگ :

متن پیام:

نظر خصوصی

 کد را وارد نمایید:

 

 

 

عکس شما

آپلود عکس دلخواه: